home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / bintel10.arc / BINTEL.DOC < prev    next >
Text File  |  1987-11-01  |  15KB  |  300 lines
  1.               BINTEL.DOC  Version 1.0  February 1987            page 1 of 6 
  2.     
  3.                      BINTEL.COM Binary-Intel Hex Convertor 
  4.                               -- R. M. Baldwin --
  5.                                         
  6.     BINTEL is a utility program for inter-converting binary files and Intel
  7.     Hex files.  Intel Hex files are a form of ASCII representation of binary
  8.     data with error-checking.  The program was written as a utility for
  9.     downloading binary files after building Steve Ciarcia's Circuit Cellar
  10.     Serial EPROM Programmer ("CCSP" or "SEPP"), described in the October
  11.     1986 issue of Byte.
  12.     
  13.     In Intel Hex format, binary data are encoded in groups of records called
  14.     'paragraphs', typically 16 bytes per paragraph.  Each paragraph is begun
  15.     with a colon (':') and ended with a carriage return.  For example:
  16.     
  17.     Binary data = (in hex)
  18.     
  19.      31 80 08 3E 89 D3 03 AF D3 00 D3 01 06 07 11 FF
  20.      FF 21 FF FF 19 DA 14 00 10 F7 3E 10 D3
  21.     
  22.     Intel Hex Representation (in ASCII) =
  23.     
  24.      :100000003180083E89D303AFD300D301060711FF27 (1st paragraph  = 16 bytes)
  25.      :0D001000FF21FFFF19DA140010F73E10D396       (2nd paragraph  = 13 bytes)
  26.      :00000001FF                                 (last paragraph =  0 bytes)
  27.     
  28.     Meaning of each field:
  29.     
  30.     Colon  Data    Address of  Paragr  Data (pairs of nibbles)    CRC
  31.            Count    1st data   Type     in ASCII form          (check sum)
  32.                       byte
  33.     
  34.       :     10       0000       00      31 80 08 3E ...    FF     27
  35.       :     0D       0010       00      FF 21 FF FF ... D3        96
  36.       :     00       0000       01      {none}                    FF
  37.     
  38.     All numbers are in upper-case Ascii hexadecimal representation.
  39.     
  40.     Data count: # data bytes in the paragraph.
  41.     Address:    Address (offset) where 1st data byte goes.
  42.     Para type:  00 = not the end yet, 01 = last paragraph.
  43.     CRC:        Check sum = 2's complement of the 8-bit addition  of the
  44.                 binary values of all the other bytes. (ie the sum of the CRC
  45.                 plus all the other bytes = 0).
  46.     Delimiter:  Each "paragraph" is ended with a carriage return.
  47.     
  48.     The last paragraph is a null paragraph, with zero data bytes; its para-
  49.     graph attribute is '01'.
  50.     
  51.     [Reference:  Bill Curlew, Circuit Cellar BBS msg #4221 (10/27/86)]
  52.     
  53.     This program is hereby donated to the public domain for non-commercial
  54.     use and distribution without restrictions (and without guarantees).  I
  55.     would appreciate feedback on the program,  especially bugs.  I can be
  56.     reached on an irregular basis on BIX (bixname rmb).
  57.     
  58.                      Ron Baldwin, Concord, CA, March, 1987.
  59.               BINTEL.DOC  Version 1.0  February 1987            page 2 of 6 
  60.     
  61.                        REQUIREMENTS FOR RUNNING BINTEL.COM
  62.                        -----------------------------------
  63.     
  64.     MS-DOS or PC-DOS 2.00 or later,  at least one disk drive. BINTEL uses
  65.     standard DOS function calls and doesn't do anything specific to IBM-
  66.     compatible hardware, so it *should* work on any MS DOS machine. I have
  67.     used it successfully  with a true blue IBM PC, several flavors of Com-
  68.     paqs, and a Hewlett-Packard HP110 portable.  It was developed on a PC
  69.     clone built from Display Telecommunications Corporation MegaBoard, with
  70.     448K RAM on the motherboard, a NEC V20 CPU, and 20 MB hard disk.
  71.     
  72.     The disk storage space required can be calculated roughly from the
  73.     following relationship:
  74.     
  75.     Hex = 13 + [(Bin div 16) * (13 + 2*16)] + [13 + 2 * (Bin mod 16)] + 1
  76.     
  77.     where Hex = size of Hex file in bytes
  78.           Bin = size of binary file in bytes
  79.     
  80.     
  81.                                  CAVEATS & NOTES
  82.                                  ---------------
  83.     
  84.       1.  Obviously, the program was written to satisfy my idiosyncrasies
  85.     and with my applications in mind. Not being a professional programmer,
  86.     the program may not be coded in the most efficient way.
  87.     
  88.       2. The binary to hex conversion was done first as a quick-and-dirty
  89.     proposition, just to download a hardware diagnostic routine; then I went
  90.     back to add the hex to binary conversion. I tried to redo it to avoid
  91.     overlapping functions, but there are still redundancies and inconsistent
  92.     ways of doing things.
  93.     
  94.       3. The assembly source is in BINTEL.ASM. It was assembled with Micro-
  95.     soft Macro Assembler (MASM) 4.00.  All the equates and macros are listed
  96.     near the beginning of the program.
  97.     
  98.       4. The buffers for input and output data can be enlarged for faster
  99.     running with large files. The variables BinBufSize and Hex BufSize con-
  100.     tain the number of bytes allocated to each. They are defined in terms of
  101.     the number of 'paragraphs', whose length in bytes is given by RecLen. As
  102.     written, the binary buffer is set at 16 paragraphs (256 bytes) and the
  103.     hex buffer is set at 3 times the binary for a total of 1 K allocated to
  104.     data buffers.
  105.     
  106.               BINTEL.DOC  Version 1.0  February 1987            page 3 of 6 
  107.     
  108.                         DIRECTIONS FOR USE OF BINTEL.COM
  109.                         --------------------------------
  110.     
  111.     BINARY FILE TO INTEL HEX FILE CONVERSION
  112.     
  113.     To convert a binary file into Intel hex format, enter BINTEL with the
  114.     name of the file to be converted.  If no extension is entered, then a
  115.     default extension will be supplied.  The default file extensions are BIN
  116.     and COM, in that order of priority; ie, if files TEST.BIN & TEST.COM are
  117.     both in the current directory, then TEST.BIN will be processed in pref-
  118.     erence to TEST.COM, unless you specifically enter BINTEL TEST.COM.  A
  119.     file with the same file name but with the extension HEX will be created
  120.     for output.  You can specify any extension by typing it in explicitly;
  121.     enter the filename with only a dot if there is no extension.
  122.     
  123.       * NOTE: no check is made to prevent over-writing an existing file. *
  124.     
  125.     Examples:
  126.     
  127.      bintel test     converts TEST.BIN to TEST.HEX
  128.      bintel test.    converts TEST     to TEST.HEX
  129.      bintel foo.bar  converts FOO.BAR  to  FOO.HEX
  130.      bintel c:\path1\path2\foobar
  131.             converts C:\PATH1\PATH2\FOOBAR.BIN to C:\PATH1\PATH2\FOOBAR.HEX
  132.     
  133.     The extension BIN was chosen to avoid confusion with MS DOS executable
  134.     COM files.  Since my application is to program 2716 EPROMs for a process
  135.     controller, using Z80 code, the starting address (offset) is set arbit-
  136.     rarily at zero.  Any relocation can usually be handled at the EPROM pro-
  137.     grammer end if needed. (Future versions may allow specifying the start-
  138.     ing address).
  139.     
  140.     Sixteen byte paragraphs are chosen by default.  If not an even multiple
  141.     of 16 bytes, the next to last paragraph will contain less than 16 data
  142.     bytes. The last paragraph is always a null paragraph with 0 data bytes.
  143.     
  144.     Paragraphs are terminated with carriage return, line feed to make the
  145.     HEX files easier to examine with text editors or from DOS. Since most
  146.     terminal emulator communications programs transmit ASCII data terminated
  147.     with carriage return only, there is no conflict, and anyway, strict
  148.     interpretation of Intel hex format should ignore anything between the
  149.     carriage return and the next ':'.  BINTEL itself is even less picky (see
  150.     below).
  151.     
  152.     The progress of the conversion is shown by displaying the hexadecimal
  153.     paragraph address continuously.  The address of the last paragraph with
  154.     data will be showing when the program ends.
  155.     
  156.               BINTEL.DOC  Version 1.0  February 1987            page 4 of 6 
  157.     
  158.     INTEL HEX FILE TO BINARY FILE CONVERSION
  159.     
  160.     The command switch /H directs BINTEL to interpret the filename as an
  161.     ASCII file in Intel Hex format and to convert it to a binary file. The
  162.     default extension for the input file is HEX, but can be overridden by
  163.     explicitly entering an extension; the output file is invariably given
  164.     the extension BIN.
  165.     
  166.      * NOTE: no check is made to prevent over-writing an existing file. *
  167.     
  168.     Examples:
  169.     
  170.       bintel test  /h     converts TEST.HEX to TEST.BIN
  171.       bintel test.asc /h  converts TEST.ASC to TEST.BIN
  172.       bintel test. /h     converts TEST     to TEST.BIN
  173.     
  174.     In processing the [ASCII] file, BINTEL ignores everything but what comes
  175.     between the ':' and the carriage return signifying the end of the para-
  176.     graph.  This means that the file can be liberally interspersed with com-
  177.     ments, if desired, so long as a colon (':') does not appear in the text.
  178.     Also, all characters other than '0' to '9' and 'A' to 'F' (upper or low-
  179.     er case) are ignored, so that spaces can be used, if desired, to improve
  180.     the legibility of the ASCII file.  Actually, even embedded carriage re-
  181.     turns and control characters can be present, since the program counts
  182.     the paragraph from the data byte value and the Intel syntax rather than
  183.     looking for the carriage return.  Some very strange looking "text" files
  184.     can thus be converted.
  185.     
  186.     Although the structure of the Intel specification appears to allow flex-
  187.     ibility in the order in which the paragraphs are arranged (for instance,
  188.     the paragraph at address 01F0 might appear earlier in the file than add-
  189.     ress 0020), BINTEL assumes that the paragraphs are arranged in contig-
  190.     uous ascending order, and assembles the binary file accordingly. If it
  191.     detects a discontinuity, it will give an error message as a warning, but
  192.     otherwise it ignores the file's address value.
  193.     
  194.     BINTEL keeps track of the CRC, and if its calculation doesn't agree with
  195.     the value stored in the paragraph, it will flag and display the offen-
  196.     ding line number and paragraph number, but will continue to process the
  197.     file.  CRC errors may indicate errors in transmitting the file if it was
  198.     up- or downloaded, or incorrect format of the hex file.
  199.     
  200.     The progress of the conversion is shown by displaying the decimal line
  201.     number (marked by carriage return) and the paragraph number continuous-
  202.     ly. The number of the last line and last paragraph will show on the
  203.     screen when it's done.
  204.               BINTEL.DOC  Version 1.0  February 1987            page 5 of 6 
  205.     
  206.                                ERROR MESSAGES
  207.                                --------------
  208.     
  209.     To keep the program relatively simple, BINTEL has only rudimentary
  210.     error-correcting features.  If it encounters a serious error, it will
  211.     exit with a 'generic' message indicating the general nature of the
  212.     problem.  It provides a return code when it exits to DOS, which can be
  213.     checked with the DOS function ERRORLEVEL, by including a statement like
  214.     'if not errorlevel 1 goto Next' in the batch file.
  215.     
  216.     The meaning of the return codes are:
  217.       0 = successful completion (no error)
  218.       1 = 'serious' error
  219.       2 = warning.
  220.     
  221.     Here is a list of the error messages and their most likely causes.
  222.     
  223.      1. Wrong DOS version ...
  224.     
  225.         BINTEL uses DOS 2.xx function calls, and requires MS DOS or PC DOS
  226.         2.0 or later.
  227.     
  228.      2. Error trying to open file:  FILENAME.IN     (return code 1)
  229.     
  230.         File not found.  Possibilities: 
  231.         a) the filename was misspelled;
  232.         b) the file doesn't have the extension BIN or COM and the extension
  233.            wasn't specified;  to process file FOOBAR (no extension) enter
  234.            "BINTEL FOOBAR." (a dot with no extension);
  235.         c) the drive or path (if used) was entered incorrectly.
  236.         d) Other possibilities are invalid characters in the name, or
  237.            anything else that normally makes DOS choke.
  238.     
  239.      3. Error reading file:  FILENAME.IN            (return code 1)
  240.     
  241.         Bad disk or corrupted directory/FAT?  It hasn't happened to me yet.
  242.     
  243.      4. Error writing file:  FILENAME.OUT           (return code 1)
  244.     
  245.         The disk is probably full. A partial file may have been stored.
  246.     
  247.      5. Error trying to close file:  FILENAME.XXX   (return code 1)
  248.     
  249.         This shouldn't happen.  It hasn't happened to me except in testing
  250.         incomplete versions of the program.
  251.     
  252.      6. Fatal Error ...                             (return code 1)
  253.     
  254.         Something inexplicable happened, and the program aborted rather than
  255.         lock up the system.
  256.     
  257.               BINTEL.DOC  Version 1.0  February 1987            page 6 of 6 
  258.     
  259.      7. Not ready error ... 
  260.           Abort, Retry, Ignore?
  261.     
  262.         DOS messages covering most I/O operations. Refer to DOS manual for
  263.         details.  Common problems are disk drive door left open, write-
  264.         protect tabs covered,  etc...
  265.     
  266.      8. Unrecognized command:  /X           (return code 0 -- no error)
  267.     
  268.         This is a warning message that has no effect on the program.  A
  269.         switch command was entered that BINTEL doesn't recognize and it was
  270.         ignored.
  271.     
  272.      9. <Address> *** WARNING! Address overflow occurred *** 
  273.         (Binary --> Hex)                    (return code 2)
  274.     
  275.         If the binary file contains more than 64 K bytes, the address coun-
  276.         ter will overflow, since Intel format only allows 2-byte addresses.
  277.         Why would you want to download bigger files anyway, at least until
  278.         '271024' EPROM chips are available?  <Address> is the offset in
  279.         hexadecimal notation of the last paragraph before overflow.
  280.     
  281.     10. <Line #> <Paragr #> CRC error ... 
  282.         (Hex --> binary)                    (return code 1)
  283.     
  284.         The CRC value calculated by BINTEL doesn't agree with the one en-
  285.         coded in the Intel Hex file.  This may be a result of an error in
  286.         transmission or an incorrect format of the hex file.  <Line #> is
  287.         the line of the ASCII file, and <Paragr #> is the number of the
  288.         paragraph in which the discrepancy occurred.  Both are in decimal
  289.         notation.   BINTEL will process the whole file,  listing all para-
  290.         graphs with errors.
  291.     
  292.     11. <Line #> <Paragr #> Address error ... 
  293.         (Hex --> binary)                    (return code 1)
  294.     
  295.         The address value calculated by BINTEL doesn't agree with the one
  296.         given in the Intel Hex file. See comments under CRC error.
  297.     
  298.                           ---  End of BINTEL.DOC  ---
  299.     
  300.